<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GInitable</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GIO 参考手册">
<link rel="up" href="failable_initialization.html" title="Failable Initialization">
<link rel="prev" href="failable_initialization.html" title="Failable Initialization">
<link rel="next" href="gio-GAsyncInitable.html" title="GAsyncInitable">
<meta name="generator" content="GTK-Doc V1.17 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="failable_initialization.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="failable_initialization.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GIO 参考手册</th>
<td><a accesskey="n" href="gio-GAsyncInitable.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#gio-GInitable.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#gio-GInitable.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry">
<a name="gio-GInitable"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="gio-GInitable.top_of_page"></a>GInitable</span></h2>
<p>GInitable — Failable object initialization interface</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="gio-GInitable.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;gio/gio.h&gt;

                    <a class="link" href="gio-GInitable.html#GInitable" title="GInitable">GInitable</a>;
struct              <a class="link" href="gio-GInitable.html#GInitableIface" title="struct GInitableIface">GInitableIface</a>;
<a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="gio-GInitable.html#g-initable-init" title="g_initable_init ()">g_initable_init</a>                     (<em class="parameter"><code><a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a> *initable</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
<a href="../glib/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="gio-GInitable.html#g-initable-new" title="g_initable_new ()">g_initable_new</a>                      (<em class="parameter"><code><a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>,
                                                         <em class="parameter"><code>const <a href="../glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_property_name</code></em>,
                                                         <em class="parameter"><code>...</code></em>);
<a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="returnvalue">GObject</span></a> *           <a class="link" href="gio-GInitable.html#g-initable-new-valist" title="g_initable_new_valist ()">g_initable_new_valist</a>               (<em class="parameter"><code><a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,
                                                         <em class="parameter"><code>const <a href="../glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_property_name</code></em>,
                                                         <em class="parameter"><code><span class="type">va_list</span> var_args</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
<a href="../glib/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="gio-GInitable.html#g-initable-newv" title="g_initable_newv ()">g_initable_newv</a>                     (<em class="parameter"><code><a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> n_parameters</code></em>,
                                                         <em class="parameter"><code><a href="../gobject/gobject-The-Base-Object-Type.html#GParameter"><span class="type">GParameter</span></a> *parameters</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="gio-GInitable.description"></a><h2>Description</h2>
<p>
<a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a> is implemented by objects that can fail during
initialization. If an object implements this interface the
<a class="link" href="gio-GInitable.html#g-initable-init" title="g_initable_init ()"><code class="function">g_initable_init()</code></a> function must be called as the first thing
after construction. If <a class="link" href="gio-GInitable.html#g-initable-init" title="g_initable_init ()"><code class="function">g_initable_init()</code></a> is not called, or if
it returns an error, all further operations on the object
should fail, generally with a <a class="link" href="gio-GIOError.html#G-IO-ERROR-NOT-INITIALIZED:CAPS"><code class="literal">G_IO_ERROR_NOT_INITIALIZED</code></a> error.
</p>
<p>
Users of objects implementing this are not intended to use
the interface method directly, instead it will be used automatically
in various ways. For C applications you generally just call
<a class="link" href="gio-GInitable.html#g-initable-new" title="g_initable_new ()"><code class="function">g_initable_new()</code></a> directly, or indirectly via a <code class="function">foo_thing_new()</code> wrapper.
This will call <a class="link" href="gio-GInitable.html#g-initable-init" title="g_initable_init ()"><code class="function">g_initable_init()</code></a> under the cover, returning <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and
setting a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> on failure (at which point the instance is
unreferenced).
</p>
<p>
For bindings in languages where the native constructor supports
exceptions the binding could check for objects implemention <a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><code class="literal">GInitable</code></a>
during normal construction and automatically initialize them, throwing
an exception on failure.
</p>
</div>
<div class="refsect1">
<a name="gio-GInitable.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="GInitable"></a><h3>GInitable</h3>
<pre class="programlisting">typedef struct _GInitable GInitable;</pre>
<p>
Interface for initializable objects.
</p>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="GInitableIface"></a><h3>struct GInitableIface</h3>
<pre class="programlisting">struct GInitableIface {
  GTypeInterface g_iface;

  /* Virtual Table */

  gboolean    (* init) (GInitable    *initable,
			GCancellable *cancellable,
			GError      **error);
};
</pre>
<p>
Provides an interface for initializing object such that initialization
may fail.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><a href="../gobject/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a> <em class="structfield"><code><a name="GInitableIface.g-iface"></a>g_iface</code></em>;</span></p></td>
<td>The parent interface.</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GInitableIface.init"></a>init</code></em> ()</span></p></td>
<td>Initializes the object.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-initable-init"></a><h3>g_initable_init ()</h3>
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_initable_init                     (<em class="parameter"><code><a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a> *initable</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
Initializes the object implementing the interface. This must be
done before any real use of the object after initial construction.
</p>
<p>
Implementations may also support cancellation. If <em class="parameter"><code>cancellable</code></em> is not <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>,
then initialization can be cancelled by triggering the cancellable object
from another thread. If the operation was cancelled, the error
<a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> will be returned. If <em class="parameter"><code>cancellable</code></em> is not <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and
the object doesn't support cancellable initialization the error
<a class="link" href="gio-GIOError.html#G-IO-ERROR-NOT-SUPPORTED:CAPS"><code class="literal">G_IO_ERROR_NOT_SUPPORTED</code></a> will be returned.
</p>
<p>
If this function is not called, or returns with an error then all
operations on the object should fail, generally returning the
error <a class="link" href="gio-GIOError.html#G-IO-ERROR-NOT-INITIALIZED:CAPS"><code class="literal">G_IO_ERROR_NOT_INITIALIZED</code></a>.
</p>
<p>
Implementations of this method must be idempotent, i.e. multiple calls
to this function with the same argument should return the same results.
Only the first call initializes the object, further calls return the result
of the first call. This is so that its safe to implement the singleton
pattern in the GObject constructor function.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>initable</code></em> :</span></p></td>
<td>a <a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>optional <a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occuring, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to
ignore.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if successful. If an error has occurred, this function will
return <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and set <em class="parameter"><code>error</code></em> appropriately if present.</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-initable-new"></a><h3>g_initable_new ()</h3>
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            g_initable_new                      (<em class="parameter"><code><a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>,
                                                         <em class="parameter"><code>const <a href="../glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_property_name</code></em>,
                                                         <em class="parameter"><code>...</code></em>);</pre>
<p>
Helper function for constructing <span class="type">GInitiable</span> object. This is
similar to <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-new"><code class="function">g_object_new()</code></a> but also initializes the object
and returns <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, setting an error on failure.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>object_type</code></em> :</span></p></td>
<td>a <a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> supporting <a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>optional <a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occuring, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to
ignore.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>first_property_name</code></em> :</span></p></td>
<td>the name of the first property, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if no
properties</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
<td>the value if the first property, followed by and other property
value pairs, and ended by <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a newly allocated <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-initable-new-valist"></a><h3>g_initable_new_valist ()</h3>
<pre class="programlisting"><a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="returnvalue">GObject</span></a> *           g_initable_new_valist               (<em class="parameter"><code><a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,
                                                         <em class="parameter"><code>const <a href="../glib/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_property_name</code></em>,
                                                         <em class="parameter"><code><span class="type">va_list</span> var_args</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
Helper function for constructing <span class="type">GInitiable</span> object. This is
similar to <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-new-valist"><code class="function">g_object_new_valist()</code></a> but also initializes the object
and returns <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, setting an error on failure.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>object_type</code></em> :</span></p></td>
<td>a <a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> supporting <a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>first_property_name</code></em> :</span></p></td>
<td>the name of the first property, followed by
the value, and other property value pairs, and ended by <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>var_args</code></em> :</span></p></td>
<td>The var args list generated from <em class="parameter"><code>first_property_name</code></em>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>optional <a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occuring, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to
ignore.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a newly allocated <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2">
<a name="g-initable-newv"></a><h3>g_initable_newv ()</h3>
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            g_initable_newv                     (<em class="parameter"><code><a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> object_type</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#guint"><span class="type">guint</span></a> n_parameters</code></em>,
                                                         <em class="parameter"><code><a href="../gobject/gobject-The-Base-Object-Type.html#GParameter"><span class="type">GParameter</span></a> *parameters</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
                                                         <em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
Helper function for constructing <span class="type">GInitiable</span> object. This is
similar to <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-newv"><code class="function">g_object_newv()</code></a> but also initializes the object
and returns <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, setting an error on failure.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>object_type</code></em> :</span></p></td>
<td>a <a href="../gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> supporting <a class="link" href="gio-GInitable.html#GInitable" title="GInitable"><span class="type">GInitable</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>n_parameters</code></em> :</span></p></td>
<td>the number of parameters in <em class="parameter"><code>parameters</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>parameters</code></em> :</span></p></td>
<td>the parameters to use to construct the object</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td>optional <a class="link" href="gio-GCancellable.html#GCancellable" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>a <a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store the error occuring, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to
ignore.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a newly allocated <a href="../gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
</div>
<div class="refsect1">
<a name="gio-GInitable.see-also"></a><h2>See Also</h2>
<a class="link" href="gio-GAsyncInitable.html#GAsyncInitable" title="GAsyncInitable"><span class="type">GAsyncInitable</span></a>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.17</div>
</body>
</html>